In this folder is a special Installer that will install a build of OpenDoc 1.0.4 with a lot of debugging features enabled. (Technically speaking, it's built with the ODDebug symbol defined as 1 instead of 0, as well as with MacsBug/traceback symbols enabled and optimizations disabled.) Using this build instead of the regular one can help you track down errors in your code, or, good heavens, in OpenDoc itself, and also just help you figure out the flow of control of OpenDoc. If you use the SYM files and OpenDoc source code provided along with this build, you will have source-level access to OpenDoc while debugging.
On the downside, the debug configuration is larger, slower, and uses more memory due to the extra debugging features. Moreover, the debug build is not officially supported. You should generally use it only when developing your own parts; re-install the regular build when running other people's components or when giving demos to your boss.
INSTALLATION
1. Run the Installer in the “Debug Installer” subfolder. That's it.
RESTORING THE REGULAR BUILD
1. Run the regular OpenDoc installer (found in the “Installing OpenDoc™” folder at the top level of the CD) again. That's it.
DETECTING WHICH BUILD IS INSTALLED
If you get confused and forget which build is installed, you can go to the OpenDoc Libraries folder (in the Extensions folder) and open the Get Info window of any of the libraries. Next to the icon, the line below the filename will include "(debug)" as part of the version name if the library is a debug version.
To check which configuration of OpenDoc is running, pull down the Apple menu and see if there is an "ODDebug" sub-menu below the About command (see below.)
SOURCE-LEVEL DEBUGGING OF OPENDOC ITSELF
Please see the “Read Me - Source Code” document in this folder. This document will explain how to install the SYM files and access the OpenDoc source code while debugging.
DEBUGGING FEATURES
• The 68K build includes MacsBug symbols, and the PPC build includes traceback tables. Both of these allow debuggers to associate function names with code. MacsBug 6.5d12 or later will show function names in disassemblies and in "sc7" stack crawls. High level debuggers will also show these names in stack crawls. (Versions 1.2 — 1.3 of the Metrowerks PPC debugger will not show tracebacks, but 1.3.1 does.)
• OpenDoc's source code includes WARN and ASSERT statements that are enabled in debug builds. These will produce debugging output via DebugStr if things go wrong. You may get warnings about illegal parameters to methods, bad reference-counting, and more. This should help track down errors in your parts.
• The debug build of OpenDoc's memory manager does a lot of sanity checking on parameters passed to it, particularly bad pointers. It also fills blocks with hex "BBBB" when they are created, and "DDDD" after they're disposed, to help track down errors where you reference storage that's either uninitialized or disposed. Memory blocks are also padded with special patterns (ascii "PPPP" before a block, "SSSS" after) to detect code that writes past the bounds of a memory block and to make it easy to see the bounds of blocks while you're debugging. It's also possible to turn on a Heap Checking mode that is very slow but will detect a damaged heap almost immediately after the damage occurs. (See the “Memory Block Structure” document for details.)
• There is a sub-menu called "ODDebug" beneath the About... command in the Apple menu, containing a variety of debugging commands. See the read-me file for this menu, in the same folder as the read-me you're reading now.
• SOMTrace is enabled in OpenDoc itself. If you turn this on (probably via the ODDebug menu) all calls to OpenDoc methods will be logged to standard output. This is helpful in determining the flow of control.
CONCLUSION
We hope you find the debug build useful. We ourselves use it heavily, not only for debugging OpenDoc itself, but also for building and testing part editors. If you think you've found a bug in OpenDoc, try to reproduce it using the debug build. While this build isn't officially supported, the extra checks in the code may detect the problem sooner and provide a better notification of what's going wrong. This will help us in trying to track down and fix the bug.
